\documentclass{article}
\usepackage{fullpage}
\author{James Gardner}
\date{\today}
\title{NNexus API}

\begin{document}

\maketitle

{\bf This document outlines the Application Programmer Interface of NNexus.}


NNexus (Noosphere Networked Entry eXtension and Unification System) is an abstraction and generalization of the automatic linking component of the Noosphere system, which is the platform of PlanetMath (planetmath.org), PlanetPhysics (planetphysics.org), and other Noosphere sites.

Users of NNexus will apply the following basic functionality to their corpus.  When an entry is rendered for display (either at display time or during offline batch processing), the text is broken down into tokens and scanned for words that invoke concepts that have been defined already (in other entries).  These words (or word tuples) are ultimately turned into hyperlinks to the corresponding entries in the output rendering.  
In addition, when the concepts are added to the collection (or the set of concept labels otherwise changes), entries containing potential invocation of these concept labels are \emph{invalidated} using a special inverted index called the \emph{invalidation index}.  This forces these entries to go through link analysis themselves by or before the next time they are displayed.

This automatic system almost completely frees the author from having to ``think about links.''  It addresses the problems of both outgoing and incoming links, with respect to a new entry or new concepts.

\section{API}
This section describes how to communicate with the NNexus server.

All request to NNexus need to be sent using the following XML form:
\begin{verbatim}
<request>
...
</request>
\end{verbatim}

where ... is any of the following requests. Note: The request must begin with a request tag followed by
a newline and the end request must have a newline before and after.

\subsection{Adding New Link Concepts}
In order to add a new concept and link you may send:
\begin{verbatim}
<addobject>
<entry>
<title>same as above</title>
<defines>thing</defines>
<defines>widget</defines>
<synonym>term3</synonym> 
<synonym>phrase of terms</synonym>
<domain>planetmath.org</domain>
<body>The body text</body>
<objid>a3db</objid>
<linkpolicy>permit 03A</linkpolicy>
<author>1</author>
<class>012A</class>
<class>02ADD</class>
</entry>
<entry>
... Same form as above.
</entry>
</addobject>
\end{verbatim}
Notice that it is possible to add multiple objects with one request.

After adding (modifying) an entry to (in) Nnexus the system will return a list of object ids that need to be
invalidated in the following form:
\begin{verbatim}
<response>
<invalid>ExternalID</invalid>
<invalid>AnotherExternalID</invalid>
</response>
\end{verbatim}

We can delete an object by passing
\begin{verbatim}
<deleteobject>
<objid>1232</objid>
<domain>wikipedia.org</domain>
</deleteobject>
\end{verbatim}

\subsection{Getting invalid objects}
A user may also request all invalidated objects by sending
\begin{verbatim}
<getinvalidobjects/>
\end{verbatim}
and the server will return all invalidated objects as
\begin{verbatim}
<update>
<invalidate>
<objid>12</objid>
<objid>123</objid>
<objid>145</objid>
<objid>1125</objid>
</invalidate>
</update>
\end{verbatim}

\subsection{Obtaining Links for New Articles or Terms}
There will be three schemes for obtaining links from Nnexus. The first two will use the entire article
and the last will only find links for terms. Note: Only the Simple Mode is currently supported.

\subsubsection{Simple Mode}
\begin{verbatim}
<article> full text of article </article>
<class>03FA2</class>
\end{verbatim}
this will return
\begin{verbatim}
<response>
<body>
full text of article with links added.
</body>
<links>
a list of the links in http://form separated by commas.
</links>
</response>
\end{verbatim}

\subsubsection{Detailed Mode}
\begin{verbatim}
<detailedreq>
<article> full text of article </article>
<class>03FA2</class>
</detailedreq>
\end{verbatim}
this will return
\begin{verbatim}
<detailedresp>
<article> full text of article </article>
<entry>
<place>12,13</place>
<option>
<link>link.to/article</link>
<domain>domain.com</domain>
</option>
<option>
<link>link.to/otherarticle</link>
<domain>otherdomain.com</domain>
</option>
</entry>
<entry>
<place>12,13</place>
<option>
<link>link.to/article</link>
<domain>domain.com</domain>
</option>
</entry>
</detailedresp>
\end{verbatim}

\subsubsection{Interactive Mode}
\begin{verbatim}
<req>
<term>term or phrase</term>
<class>03FA2</class>
<dclass>desired classification of article to link to</dclass>
</req>
\end{verbatim}
Note:  dclass is optional
After sending this information the server will return
\begin{verbatim}
<resp>
<link>http://link.to/the_article</link>
<linkid>12313</linkid>
</resp>
\end{verbatim}

\subsection{Exporting Concept Labels}
To access the concept labels that Nnexus is currently using you may pass
\begin{verbatim}
<getconcepts>
<domain>domain.org</domain>
<domain>otherdomain.org</domain>
</getconcepts>
\end{verbatim}
and the server will return the xml config files as
\begin{verbatim}
<config> 
<domain>domain.org</domain>
<contents>contents of domain.org config file</contents>
</config>
<config>
<domain>otherdomain.org</domain>
<contents>contents of otherdomain.org config file</contents>
</config>
\end{verbatim}

\section{Examples}
Contact James Gardner (pebbler@gmail.com) for examples and help.

\end{document}